---
type: integration
title: '@astrojs/netlify'
description: "Apprenez à utiliser l'adaptateur @astrojs/netlify pour déployer votre projet Astro."
sidebar:
  label: Netlify
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/netlify/'
category: adapter
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import Since from '~/components/Since.astro';

Cet adaptateur permet à Astro de déployer vos [routes et fonctionnalités rendues à la demande](/fr/guides/on-demand-rendering/) sur [Netlify](https://www.netlify.com/), y compris [les îlots de serveurs](/fr/guides/server-islands/), les [actions](/fr/guides/actions/) et les [sessions](/fr/guides/sessions/).

Si vous utilisez Astro comme générateur de site statique, vous n'avez besoin de cet adaptateur que si vous utilisez des services Netlify supplémentaires qui nécessitent un serveur (p. ex. [CDN d'images de Netlify](#prise-en-charge-du-cdn-image-de-netlify)). Sinon, vous n’avez pas besoin d’un adaptateur pour déployer votre site statique.

Apprenez à déployer votre site Astro dans notre [guide de déploiement Netlify](/fr/guides/deploy/netlify/).

## Pourquoi Astro Netlify

[Netlify](https://www.netlify.com/) est une plateforme de déploiement qui vous permet d'héberger votre site en vous connectant directement à votre dépôt GitHub. Cet adaptateur améliore le processus de compilation d'Astro pour préparer votre projet à être déployé via Netlify.

## Installation

Astro inclut une commande `astro add` pour automatiser l'installation des intégrations officielles. Si vous préférez, vous pouvez [installer les intégrations manuellement](#installation-manuelle) à la place.

Ajoutez l'adaptateur Netlify pour activer le rendu à la demande dans votre projet Astro avec la commande `astro add`.
Cela installera `@astrojs/netlify` et apportera les changements appropriés à votre fichier `astro.config.mjs` en une seule étape.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add netlify
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add netlify
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add netlify
  ```
  </Fragment>
</PackageManagerTabs>

Désormais, vous pouvez activer [le rendu à la demande par page](/fr/guides/on-demand-rendering/#activation-du-rendu-à-la-demande) ou définir la configuration de sortie de votre compilation sur `output: 'server'` pour [restituer toutes vos pages par défaut sur le serveur](/fr/guides/on-demand-rendering/#mode-server).

### Installation manuelle

Tout d'abord, installez l'adaptateur Netlify dans les dépendances de votre projet en utilisant votre gestionnaire de paquets préféré :

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/netlify
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/netlify
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/netlify
  ```
  </Fragment>
</PackageManagerTabs>

Ensuite, ajoutez l'adaptateur à votre fichier `astro.config.*` :

   ```js title="astro.config.mjs" ins={2, 6}
    import { defineConfig } from 'astro/config';
    import netlify from '@astrojs/netlify';

    export default defineConfig({
       // ...
       adapter: netlify(),
    });
   ```

## Utilisation

[Lisez le guide de déploiement complet ici.](/fr/guides/deploy/netlify/)

Suivez les instructions pour [compiler votre site localement](/fr/guides/deploy/#compiler-votre-site-localement). Après la compilation, vous aurez un dossier `.netlify/` contenant à la fois [les fonctions de Netlify](https://docs.netlify.com/functions/overview/) dans le dossier `.netlify/functions-internal/` et [les fonctions Edge de Netlify](https://docs.netlify.com/edge-functions/overview/) dans le dossier `.netlify/edge-functions/`.

Pour déployer votre site, installez la [CLI de Netlify](https://docs.netlify.com/cli/get-started/) et exécutez :

```sh
netlify deploy
```

L'[article de blog de Netlify sur Astro](https://www.netlify.com/blog/how-to-deploy-astro/) et la [documentation de Netlify](https://docs.netlify.com/integrations/frameworks/astro/) fournissent plus d'informations sur la manière d'utiliser cette intégration pour déployer vers Netlify.

### Exécution du middleware Astro sur les fonctions Edge de Netlify

Tout middleware Astro est appliqué aux pages pré-rendues au moment de la compilation, et aux pages pré-rendues au moment de l'exécution.

Pour implémenter des redirections, des contrôles d'accès ou des en-têtes de réponse personnalisés pour les pages pré-rendues, exécutez votre middleware sur les fonctions Edge de Netlify en activant l'option [`edgeMiddleware`](/fr/reference/adapter-reference/#edgemiddleware) :

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    edgeMiddleware: true,
  }),
});
```

Lorsque `edgeMiddleware` est activé, une fonction edge exécutera votre code middleware pour toutes les requêtes, y compris les ressources statiques, les pages pré-rendues et les pages rendues à la demande.

Pour les pages rendues à la demande, l'objet `context.locals` est sérialisé en utilisant du JSON et envoyé dans un en-tête pour la fonction serverless, qui effectue le rendu. Comme mesure de sécurité, la fonction serverless refusera de servir les requêtes avec une réponse `403 Forbidden` à moins qu'elles ne proviennent de la fonction edge générée.

### Accès au contexte Edge depuis votre site

Les fonctions Edge de Netlify fournissent un [objet de contexte](https://docs.netlify.com/edge-functions/api/#netlify-specific-context-object) qui comprend des métadonnées sur la demande, telles que l'IP de l'utilisateur, les données de géolocalisation et les cookies.

Cet objet est accessible via l'objet `Astro.locals.netlify.context` :

```astro
---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---

<h1>Bonjour, aimable visiteur de {city} !</h1>
```

Si vous utilisez TypeScript, vous pouvez [obtenir des typages corrects](/fr/guides/typescript/#extension-des-types-globaux) en mettant à jour `src/env.d.ts` pour utiliser `NetlifyLocals` :

```ts title="src/env.d.ts"
type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals

declare namespace App {
  interface Locals extends NetlifyLocals {
    // ...
  }
}
```

Ceci n'est pas disponible sur les pages pré-rendues.

### Prise en charge du CDN Image de Netlify

Cet adaptateur utilise par défaut le [CDN Image de Netlify](https://docs.netlify.com/image-cdn/overview/) pour transformer les images à la volée sans impacter sur les temps de compilation.
Il est implémenté en utilisant un [service d'images d'Astro](/fr/reference/image-service-reference/) sous le capot.

Pour ne pas utiliser l'optimisation d'image à distance du CDN de Netlify, utilisez l'option `imageCDN` :

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    imageCDN: false,
  }),
});
```

Si vous utilisez des images hébergées sur un autre domaine, vous devez autoriser les chaînes de domaines ou d'URL en utilisant les options de configuration [`image.domains`](/fr/reference/configuration-reference/#imagedomains) ou [`image.remotePatterns`](/fr/reference/configuration-reference/#imageremotepatterns) :

```js title="astro.config.mjs" ins={7-9}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
    // ...
    adapter: netlify(),
    image: {
      domains: ['exemple.com'],
    },
});
```
Pour plus d'informations, voir [le guide d'autorisation des images distantes](/fr/guides/images/#autoriser-les-images-distantes). Cela n'est pas nécessaire pour les images hébergées sur le même domaine que votre site.

### Sites statiques avec l'adaptateur Netlify

Pour les sites statiques (`output: 'static'`) hébergés sur Netlify, vous n'avez généralement pas besoin d'adaptateur. Cependant, certaines fonctionnalités de déploiement ne sont disponibles qu'à travers un adaptateur.

Les sites statiques devront installer cet adaptateur pour utiliser et configurer le [service d'image de Netlify](#prise-en-charge-du-cdn-image-de-netlify).

Si vous utilisez la configuration `redirects` dans votre configuration Astro, l'adaptateur Netlify peut être utilisé pour traduire cette configuration au format `_redirects` approprié.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify(),
  redirects: {
    '/blog/ancien-article': '/blog/nouvel-article',
  },
});
```

Une fois que vous avez exécuté `astro build`, il y aura un fichier `dist/_redirects`. Netlify l'utilisera pour router correctement les pages en production.

:::note
Vous pouvez toujours inclure un fichier `public/_redirects` pour les redirections manuelles. Toutes les redirections que vous spécifiez dans la configuration des redirections sont ajoutées à la fin de la vôtre.
:::

### Sessions

L'[API Sessions](/fr/guides/sessions/) d'Astro vous permet de stocker facilement les données utilisateur entre chaque requête. Ceci peut être utilisé pour des éléments tels que les données et préférences utilisateur, les paniers d'achat et les identifiants d'authentification. Contrairement au stockage des cookies, la taille des données est illimitée et elles peuvent être restaurées sur différents appareils.

Astro configure automatiquement [Netlify Blobs](https://docs.netlify.com/blobs/overview/) pour le stockage de session lors de l'utilisation de l'adaptateur Netlify. Si vous préférez utiliser un autre pilote de stockage de session, vous pouvez le spécifier dans votre configuration Astro. Consultez [la référence de configuration `session`](/fr/reference/configuration-reference/#sessiondriver) pour plus de détails.

### Mise en cache des pages

Les pages rendues à la demande sans contenu dynamique peuvent être mises en cache pour améliorer les performances et réduire l'utilisation des ressources.
L'activation de l'option `cacheOnDemandPages` dans l'adaptateur mettra en cache toutes les pages rendues par le serveur pour une durée maximale d'un an :

```ts title="astro.config.mjs" ins={4}
export default defineConfig({
  // ...
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});
```

Cela peut être modifié page par page en ajoutant des en-têtes de mise en cache à votre réponse :

```astro title="pages/index.astro"
---
import Layout from '../components/Layout.astro';

Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');
---

<Layout title="Astro on Netlify">
  {new Date()}
</Layout>
```

Grâce au [contrôle précis du cache](https://www.netlify.com/blog/swr-and-fine-grained-cache-control/), Netlify prend en charge
les en-têtes de cache standard comme `CDN-Cache-Control` ou `Vary`.
Reportez-vous à la documentation pour en savoir plus sur la mise en place, par exemple, de la mise en cache TTL (time to live) ou SWR (stale while revalidate) : https://docs.netlify.com/platform/caching

### Protection contre les décalages de version

<p><Since v="6.6.0" pkg="@astrojs/netlify" /></p>

La protection anti-décalage (ou « skew protection » en anglais) de Netlify garantit que les utilisateurs accédant à votre site pendant un déploiement continuent de recevoir le contenu de la même version. L'adaptateur Netlify configure automatiquement la protection anti-décalage pour les fonctionnalités Astro telles que les actions, les îlots de serveurs, les transitions de vue et les demandes de prélecture en injectant l'ID de déploiement actuel dans les requêtes internes. Cela évite les incompatibilités de version entre le client et le serveur lors des déploiements actifs.

Bien qu'Astro ajoute automatiquement l'en-tête de protection anti-décalage pour ses fonctionnalités intégrées, si vous effectuez vos propres demandes de récupération sur votre site, vous pouvez inclure l'en-tête manuellement à l'aide de la variable d'environnement `DEPLOY_ID` :

```js
const response = await fetch('/api/endpoint', {
  headers: {
    'X-Netlify-Deploy-ID': import.meta.env.DEPLOY_ID,
  },
});
```

### Inclure ou exclure des fichiers des fonctions Netlify

Lors du déploiement d'un site Astro avec rendu à la demande sur Netlify, les fonctions générées tracent et incluent automatiquement les dépendances du serveur. Cependant, vous devrez peut-être personnaliser les fichiers inclus dans vos fonctions Netlify.

#### `includeFiles`

<p>
**Type :**  `string[]`<br />
**Par défaut :** `[]`<br />
<Since v="5.3.0" />
</p>

La propriété `includeFiles` vous permet de spécifier explicitement des fichiers supplémentaires qui doivent être regroupés avec votre fonction. Ceci est utile pour les fichiers qui ne sont pas automatiquement détectés comme dépendances, tels que :
- les fichiers de données chargés à l'aide des opérations `fs`
- les fichiers de configuration
- les fichiers de modèles

Fournissez un tableau de fichiers supplémentaires à inclure avec les chemins de fichiers relatifs à la [racine (`root`)](/fr/reference/configuration-reference/#root) de votre projet. Les chemins absolus peuvent ne pas fonctionner comme prévu.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    includeFiles: ['./mes-donnees.json'], // chemin relatif à `root`
  }),
});
```

#### `excludeFiles`

<p>
**Type :**  `string[]`<br />
**Par défaut :** `[]`<br />
<Since v="5.3.0" />
</p>

Vous pouvez utiliser la propriété `excludeFiles` pour empêcher le regroupement de fichiers spécifiques qui seraient autrement inclus. Cela est utile pour :
- Réduire la taille du regroupement
- Exclure des binaires volumineux
- Empêcher le déploiement de fichiers indésirables

Fournissez un tableau de fichiers spécifiques à exclure avec des chemins de fichiers relatifs à la [racine (`root`)](/fr/reference/configuration-reference/#root) de votre projet. Les chemins absolus peuvent ne pas fonctionner comme prévu.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    excludeFiles: ['./src/un_gros_fichier.jpg'], // chemin relatif à `root`
  }),
});
```

#### Utilisation des motifs glob

`includeFiles` et `excludeFiles` prennent en charge les [motifs glob](/fr/guides/imports/#motifs-glob) pour faire correspondre plusieurs fichiers :

```js title="astro.config.mjs" ins={7, 10-11}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  adapter: netlify({
    includeFiles: [
      './data/**/*.json'
    ],
    excludeFiles: [
      './node_modules/package/**/*',
      './src/**/*.test.js'
    ]
  }),
});
```

### Fonctionnalités de développement local

Lors de l'exécution de `astro dev`, l'adaptateur active plusieurs fonctionnalités de la plateforme Netlify pour garantir que l'environnement correspond le plus possible à la production. Celles-ci comprennent :

- Un serveur local pour [le CDN Image de Netlify](https://docs.netlify.com/build/image-cdn/overview/). Il est utilisé par défaut pour les [images](#prise-en-charge-du-cdn-image-de-netlify).
- Un serveur local pour [Netlify Blobs](https://docs.netlify.com/build/data-and-storage/netlify-blobs/). Il est utilisé par défaut pour les [sessions](#sessions).
- Les [redirections, réécritures](https://docs.netlify.com/manage/routing/redirects/overview/) et [en-têtes](https://docs.netlify.com/manage/routing/headers/) définis dans votre configuration Netlify
- Un accès au [contexte Netlify Edge](#accès-au-contexte-edge-depuis-votre-site) dans les pages à la demande
- Les [variables d'environnement](https://docs.netlify.com/build/environment-variables/overview/) de votre site Netlify

Celles-ci fonctionnent mieux lorsque votre site local est [lié à un site Netlify](https://docs.netlify.com/api-and-cli-guides/cli-guides/get-started-with-cli/#link-and-unlink-sites) à l'aide de `netlify link`.

Vous pouvez activer ou désactiver certaines de ces fonctionnalités à l'aide de l'option [`devFeatures`](#devfeatures) dans la configuration de votre adaptateur. Par défaut, toutes les fonctionnalités sont activées, à l'exception des variables d'environnement.

#### `devFeatures`

<p>
**Type :** `boolean | object`<br />
**Par défaut :** `{ images: true, environmentVariables: false }`<br />
<Since v="6.5.1" pkg="@astrojs/netlify"/>
</p>

L'option `devFeatures` peut être soit un booléen pour activer ou désactiver toutes les fonctionnalités, soit un objet pour activer des fonctionnalités spécifiques.

```js title="astro.config.mjs" ins={7-12}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    devFeatures: {
      // Active la prise en charge du CDN Image de Netlify dans dev. La valeur par défaut est true.
      images: false, 
      // Injecte les variables d'environnement Netlify dans dev. La valeur par défaut est false.
      environmentVariables: true, 
    },
  }),
});
```

##### `devFeatures.images`

<p>
**Type :** `boolean`<br />
**Par défaut :** `true`<br />
<Since v="6.5.1" pkg="@astrojs/netlify"/>
</p>

Active la prise en charge locale du [CDN Image de Netlify](https://docs.netlify.com/build/image-cdn/overview/) en cours de développement.

Cela utilise une version locale du CDN Image de Netlify, plutôt que le service d'images d'Astro par défaut.

##### `devFeatures.environmentVariables`

<p>
**Type :** `boolean`<br />
**Par défaut :** `false`<br />
<Since v="6.5.1" pkg="@astrojs/netlify"/>
</p>

Injecte les variables d'environnement de votre site Netlify dans l'environnement de développement.

Cela vous permet d'utiliser les mêmes valeurs en développement qu'en production. Consultez [la documentation de Netlify sur les variables d'environnement](https://docs.netlify.com/build/environment-variables/overview/) pour plus d'informations, notamment sur la manière d'utiliser différentes variables pour différents environnements.

## Fonctionnalités expérimentales

Les fonctionnalités suivantes sont également disponibles, mais peuvent être sujettes à des modifications non rétrocompatibles lors de futures mises à jour. Veuillez suivre attentivement le [journal des modifications de `@astrojs/netlify`](https://github.com/withastro/astro/tree/main/packages/integrations/netlify/CHANGELOG.md) pour être informés des mises à jour si vous utilisez ces fonctionnalités dans votre projet.

### `experimentalStaticHeaders`

<p>
  **Type :** `boolean` <br />
  **Par défaut :** `false`<br />
  <Since v="6.4.0" pkg="@astrojs/netlify"/>
</p>

Active la définition d'en-têtes personnalisés pour les pages pré-rendues dans la configuration de Netlify.

Si cette option est activée, l'adaptateur enregistrera [les en-têtes statiques dans le fichier de configuration de l'API Framework](https://docs.netlify.com/frameworks-api/#headers) lorsqu'ils sont fournis par les fonctionnalités d'Astro, telles que la politique de sécurité du contenu.

Par exemple, lorsque la [politique de sécurité du contenu expérimentale](/fr/reference/experimental-flags/csp/) est activée, `experimentalStaticHeaders` peut être utilisée pour ajouter les en-têtes CSP (`headers`) à votre configuration Netlify, au lieu de créer un élément `<meta>` :

```js title="astro.config.mjs" {9}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  experimental: {
    csp: true
  },
  adapter: netlify({
    experimentalStaticHeaders: true 
  })
});
```


## Exemples

* Le [modèle de démarrage Astro avec Netlify Edge](https://github.com/sarahetter/astro-netlify-edge-starter) fournit un exemple et un guide dans le fichier README.

* [Parcourir les projets Astro Netlify sur GitHub](https://github.com/search?q=path%3A**%2Fastro.config.mjs+%40astrojs%2Fnetlify\&type=code) pour plus d'exemples !


[astro-integration]: /fr/guides/integrations-guide/
